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Prefatory Note \ 

Certain sections of the following reference manual are 
written in a primer-like style, especially parts of the 
introduction and the discussion of macros. However, it is 
assumed that the reader is familiar with the logical operation 
of general -purpose digital computers, and, in particular, is 
acquainted with the SDS 9^0 instruction set (see the SDS 
publication, SDS 9^0 Computer Reference Manual , No. 90 06 UOA, 
August, 1966, or the Project GENIE document, SDS 930 Instructions , 
Document R-27, October 11, I966). 
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2) For a description of the implementation of NARP see 
Project GENIE document, Implementation of NARP , Document M-l6, 
January 25, 1968. 
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1.0 Introduction 

NARP (new ARPAS) is a one-pass assembler for the SDS 9*4-0 
with literal, subprogram, conditional assembly, and macro 
facilities. The source language for NARP, primarily a one-for- 
one representation of machine language written in symbolic form, 
is very similar to that for ARPAS (another assembler for the 9^0), 
but there are notable exceptions making it necessary to do a 
certain amount of transliteration to convert an ARPAS program to 
a NARP program. No further mention will be made of ARPAS 
in this manual; for more details see ARPAS, Reference Manual for 
Time-Sharing Assembler for the SDS 930 , Doc. No. R-26, 
February 2k, 1967. 

To motivate the various facilities of the assembler, the 
following pseudo-historical development of assembly languages 
is presented. 

1.1 Pseudo-history of assembly languages 

A program stored in the main memory of a modern computer 
consists of an array of tiny circular magnetic fields, some 
oriented clockwise, others oriented counterclockwise. Obviously, 
if a programmer had to think in these terms when he sat down 
to write a program, few problems of any complexity would be 
solved by computers, and the cost of keeping programmers sane would 
be prohibitive. To remedy this situation, utility programs 
called assemblers have been developed to translate programs 
from a symbolic form convenient for human use to the rather 
tedious bit patterns that the computer handles. At first these 
assemblers were quite primitive, little more than number converters, 
in fact. Thus, for example: 

Tag Opcode Address 



76 0J&00 

55 00^01 

r ~ 35 <W 2 



1-2 



would be converted into three computer instructions which would 
add together the contents of cells 400 and 1+01 and place the 
result in cell 402. An assembler for doing this type of conver- 
sion is trivial to construct. 

After a time, some irritated programmer who could never 
remember the numerical value of the operation "load the A register 
with the contents of a cell of memory" decided that it would not 
be too difficult to write a more sophisticated assembler which 
would allow him to write a short mnemonic word in place of the 
number representing the hardware operation. Thus, the sequence 
of instructions shown above became: 

LDA 001+00 
ADD 00401 
STA 00402 

This innovation cost something, however, namely the assembler 
had to be more clever. But not much more clever. The programmer 
in charge of the assembler simply added a table to the assembler 
which consisted of all the mnemonic operation names ( opcodes ) 
and an associated number, namely the numerical value of the 
opcode. When a mnemonic name, say 'ADD', was encountered by the 
assembler during the conversion of a program, the opcode table 
was scanned until the mnemonic name was found; then the associated 
numerical value (in this case, 55) was used to form the instruc- 
tion. Within a month, no programmer could tell you the numerical 
value of XMA.. 

In a more established field, the innovation of these mnemonic 
names would have been quite enough for many years and many 
theoretical papers. However, programmers are an irritable lot, 
and furthermore, are noted for their ability to get rid of sources 
of irritation, either by writing more clever programs or by 
asking the engineers to refrain from making such awkward machines. 
And the use of numbers to represent addresses in memory was a 
large source of irritation. To see this we need another example: 



CIA 

LDX 00400 
2 STA 00507 
BRX 00300 
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( ,; Assuming cell 1+00 contains -7, this sequence stores zeroes in 

cells 500 through 506 provided that the sequence is loaded in 
memory so that the STA instruction is in cell 300 (otherwise, 
the BRX instruction would have to be modified). This was the 
crux of the problem: Once a program was written, it could only- 
run from a fixed place in memory and could only operate on fixed 
cells in memory. This was especially awkward when a program was 
changed, since inserting an instruction anywhere in a program would 
generally require changes in many, many addresses. One day a 
clever programmer saw that this problem could be handled by a 
generalization of the scheme used to handle opcodes, namely, 
let the programmer use symbolic names ( symbols ) for addresses 
and have the assembler build a table of these symbols as they 
are defined and then later distribute the numerical values 
associated with the symbols as they are used. Thus the example 
becomes: 

V_J LOOP 

(Note that at the same time the programmer decided to move 
the tag field to after the address field (simply for the sake 
of readability) and to even dispense with it entirely in case 
it was zero,) The assembler now has two tables, the fixed opcode 
table with predefined names in it, and a symbol table which is 
initially empty. There is also a special cell in the assembler 
called the location counter (LC) which keeps track of how many 
cells of program have been assembled; LC is initially zero. 
There is another complication: In the above example, when the 
symbol TABLEN is encountered, it may not be defined yet, so the 
assembler doesn't know what numerical value to replace it with. 
There are several clever ways to get around this problem, but 
the most obvious is to have the assembler process the program 
to be assembled twice . Thus, the first time the assembler scans 
the program it is mainly interested in the symbol definitions 
C j in the left margin (a symbol used to represent a memory address 

is called a label ) . In our example, when LOOP is encountered, 
it is stored in the symbol table and given the value 2 (because 



CIA 




LDX 


TABLEN 


STA 


TABEND, 2 


BRX 


LOOP 
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CLA 




LDB 


EIGHT 


LDX 


TABLEN 


STP 


TABEND, 2 


EAX 


1,2 


BRX 


LOOP 
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it is preceded by two cells; remember that LC keeps track of 
this). At the end of pass 1, all symbols defined in the program 
are in the symbol table with numerical values corresponding to 
their addresses in the memory. So when pass 2 begins, the symbol 
table is used exactly a s the opcode table is used, namely, when, 
for example, LOOP is encountered in the BRX instruction above, 
it is looked up in the symbol table and replaced by the value 2. 
If the program should later be changed, for example to 



LOOP 



then the assembler will automatically fix up LOOP to have the 
value 3 (because of the inserted LDB instruction) and will 
convert BRX LOOP to BRX 3 instead of to BRX 2 as before. Thus, 
the programmer can forget about adjusting a lot of numerical 
addresses and let the assembler do the work of assigning new 
values to the symbols and distributing them to the points where 
the symbols are used. In addition to the greater flexibility 
achieved, symbols with mnemonic value can be used to make the 
program more readable. 

The use of symbols to stand for numerical values which 
are computed by the assembler and not the programmer is the basic 
characteristic of all assembly languages. Its inception was 
a fundamental breakthrough in machine language programming, dispensing 
with much dullness and tedium. And a new breed of programmer 
was born: the assembler- writer. To justify his existence, the 
assembler-writer began to add all sorts of bells and whistles 
to his products; the primary ones are discussed in the next 
section (with reference to KARP). 

1.2 Assembly languages: some basic constituents and concepts 

Times : assembly time: when a program in symbolic form is 

converted by an assembler to binary 
(relocatable) program form. 
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load time : when a binary program is converted by a loader to 
actual machine language in the main memory of 
the computer. 

run time: when the loaded program is executed. 

assembler loader 
source program — ^ binary program — ^ object program 

Expressions : The idea of using a symbol to stand for an address 
is generalized to allow an arithmetic expression (possibly 
containing symbols) to stand for an address. Thus, some calcu- 
lations can be performed at assembly time rather than at run 
time, making programs more efficient. 

Literals : Rather than writing IDA Ml and somewhere else defining 
Ml to be a cell containing -1, the literal capability allows the 
programmer to write the contents of a cell in the address field 
instead of the address of a cell. To indicate this, the expression 
is preceded by '='. The assembler automatically assigns a cell 
for the value of the expression (at the end of the program) : 

CIA 

LDB =8 

LDX =-l6*2 

LOOP STP TABBEG+l6*2,2 

EAX 1,2 

BRX LOOP 

Relocation : A relocatable program is one in which memory locations 

have been computed relative to the first word or origin of the 

program. A loader (for this assembler, DDT) can then place the 

assembled program into core beginning at whatever looation may be 

specified at load time. Placement of the program involves a 

small calculation. For example, if a memory reference is to the 

nth word of a program, and if the program is loaded beginning 

at location k, the loader must transform the reference into 

absolute location n+k. This calculation should not be done to 

each word of a program since some machine instructions (shifts, 

for example) do not refer to memory locations. It is therefore 

necessary to inform the loader whether or not to relocate the 

address for each word of the program. Relocation information is f*\ 

determined automatically by the assembler and transmitted as a 

relocation factor (rfactor). Constants or data may similarly 
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require relocation, the difference here being that the relocation 

calculation should apply to all 2k bits of the 9^0 word, not just 

to the address field. The assembler accounts for this difference \ t 

automatically. 

Subprograms and external symbols : Programs often become quite 

large or fall into logical divisions which are almost independent. 

In either case it is convenient to break them into pieces and 

assemble (and even debug) them separately. Separately assembled 

parts of the same program are called subprograms (or packages ) . 

Before a program assembled in pieces as subprograms can be run it 

is necessary to load the pieces into memory and link them. The 

symbols used in a given subprogram are generally local to that 

subprogram. Subprograms do, however, need to refer to symbols 

defined in other subprograms. The linking process takes care of 

such cross-references. Symbols used for it are called external 

symbols . 

Directives : A directive (pseudo-opcode is a message to the 

assembler serving to change the assembly process in some way. 

Directives are also used to create data: 

LIST 
MESSAGE TEXT 'THIS IS A PIECE OF TEXT' 
START LDA ALPHA 

The LIST directive will cause the program to be listed during 
assembly, while the TEXT directive will cause the following text 
to be stored in memory, four characters to a word. 
Conditional assembly : It is frequently desirable to permit the 
assembler to either assemble or skip a block of statements 
depending on the value of an expression at assembly time; this 
is called conditional assembly . With this facility, totally 
different object programs can be generated, depending on the values 
of a few parameters. 

Macros : A macro is a block of text defined somewhere in the 
program and given a name. Later references to this name cause 
the reference to be replaced by the block of text. Thus, the 
macro facility can be thought of as an abbreviation or shorthand 
notation for one or more assembly language statements. The macro 
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V_y facility is more powerful than this, however, since a macro may- 

have formal arguments which are replaced by actual arguments when 
the macro is called. 

One -pass assembly : Instead of processing a source program twice v 
as was described above (section l.l), NARP accomplishes the same 
task in one scan over the source program. The method used is 
rather complex and is described elsewhere, ( implementation of 
NARP, Doc. M-l6) 
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2.0 Basic constituents of MRP 



2.1 Character set 



All the characters listed in Appendix B have meaning in 
NARP except for '?• and ' V. The following classification of 
the character set is useful; 

JL@*C"w©3r • _ A - * o 

octal digit j 0-7 

digit*. 0-9 

alphanumeric character: letter or digit or colon 

terminator; < , ; blank CR (denotes carriage return) 

operator : !#$&* + -/<=><£? T 

delimiter: "$'()[].«_ 

The multiple-blank character (l 3 5 8 ) may appear anywhere that a 
blank is allowed. All characters with values greater than 77« are 
ignored except for multiple-blank character (l35o) and carriage 
return (155q)* 

2.2 Statements and format 

The logical unit of input to NARP is the statement, a sequence 
of characters terminated by a semi-colon or a carriage return. 
There are five kinds of statements: < 

1. empty: A statement may consist of no characters at all, or only 
of blank characters, 

2, comment: If the very first character of a statement is an 
asterisk, then the entire statement is treated as a 
comment containing information for a human reader. 
Such statements generate no output. 

The format for the next three kinds of statements is split into 

four fields: 

label field : This field is used primarily for symbol definition; 

it begins with the first character of the statement and 
r •"*"% ends on the first non-alphanumeric character (usually 8 

blank). 
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opcode field : This field contains a directive name, a macro 
name, or an instruction (i.e., any opcode other than a 
directive or macro). The field begins with the first 
non-blank character after the label field and terminates 
on the first non-alphanumeric character; legal terminators 
for this field are blank, asterisk, semi-colon, and 
carriage return. 

operand field ; The operand for an instruction, macro, or 

directive appears in this field, it begins with the first 
non-blank character following the opcode field and terminates 
on the first blank, semi-colon, or carriage return. Note 
that a statement may terminate before the operand field. 

comment field : This field contains no information for NARP but 
may be used to help clarify a program for a human reader. 
The field starts with the first non-blank character after 
the operand field (or after the opcode field if the opcode 
takes no operand) and ends on a semi-colon or carriage return. 

Now we continue describing the kinds of statements: 
3. instruction: If the opcode field of a statement does not contain 
a directive name or a macro name, then the statement is 
an instruction. An instruction usually has an expression 
as an operand and generates a single machine word of 
program. See section 3 for a detailed description of 
instructions. 
k. directive: If a directive name appears in the opcode field, then 
it is a directive statement. The action of each directive 
is unique and thus each one is described separately (in 
section h) . 
5. macro: A macro name in the opcode field of a statement indicates 
that the body of text associated with the macro name should 
be processed (see section 5). 

Example of various kinds of statements: 

* FOLLOWING ARE TWO DIRECTIVES (MACRO, ENDM) WHICH DEFINE 

* THE MACRO SKAP 

SKAP MACRO; SKA AB7; ENDM 






• « 
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* NOW SKAP IS CALLED: 

LDA ALPHA 

SKAP; BRU BAD IF NEGATIVE THEN ERROR 
OKAY ADD BETA NOW A=ALPHA+BETA ; BRU GOOD >, 



In subsequent sections the details of instructions, directives, 
and macros will be explained, but first some basic constituents 
and concepts common to all of these statements will be discussed. 

2.3 Symbols, numbers, and string constants 

Any string of alphanumeric characters not forming a number 
is a symbol, but only the first six characters distinguish the 
symbol (thus QI23I+5 is the same symbol as 0123^56). Note that 
a symbol may begin with a digit, and that a colon is treated as 
a letter (as a matter of good programming practice, colons should 
be used rarely in symbols, although they are often useful in 
macros and other obscure places to avoid conflicts with other 
names). In the next section the definition and the rf actors 
of symbols are discussed. 

A number is any one of the following: 

a) A string of digits 

b) A string of digits followed by the letter 'D' 

c) A string of octal digits followed by the letter 'B' 

d) A string of octal digits followed by the letter 'B' 
followed by a single digit. 

A D-suffix indicates the number is decimal, whereas a B- suffix 
indicates an octal number. If there is no suffix, then the 
current radix is used to interpret the number (the current 
radix is initially 10 but it may be changed by the OCT and DEC 
directives). If the digit 8 or 9 is encountered in an octal 

number, then an error message is typed. If the value of a 

23 
number exceeds 2 -1 overflow results; NARP does not check for 

this condition, and in general it should be avoided. A B-suffix 

followed by a digit indicates an octal scaling; thus, 7 l +B3=7 1 +000B . 

Examples : 

symbols: START 1M CALCULATE 1^D2 l^BlO 

numbers: lU 18d 773B 777B5 13B9 
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LM 


WORD 


SKE 


= 'GO' 


HRU 


STOP 



Both numbers and string constants are absolute, i.e., their 
rf actor is zero. 

2.k Symbol definitions 

Since NARP is a one -pass assembler, the statement that a 

symbol or expression is "defined" usually means that it is defined 

at that instant and not somewhere later in the program. Thus, 

assuming ALPHA is defined nowhere else, the following 

BETA EQU ALPHA 
ALPHA BSS 3 

is an error because the EQU directive demands a defined operand 
and ALPHA is not defined until the next statement. This convention 
is not strictly adhered to, however, since sometimes the state- 
ment "XYZ is not defined" will mean that XYZ is defined nowhere 
in the program. 
(~) A symbol is defined in one of two ways: by appearing as a 

label or by being assigned a value with an EQU directive (or 






2-k 

O H 

A string constant is one of the following: 

a) A string of 1 to 3 characters enclosed in double 
quotes ("). 

b) A string of 1 to k characters enclosed in single 
quotes (')• 

In the first case the characters are considered to be 8 bits 
each (thus only 3 can be stored in one machine word), while in 
the second case they are considered to be 6 bits each. In both 
cases, strings of less than the maximum length (3 or k, as the 
case may be) are right-justified. Thus 

'A' = * A' = *A" = " A" 

where j_ denotes a blank. If a string constant is too long, then 
an error message is typed and only the first 3 (or h) characters 
are taken. Normally string constants are not very useful in 
address computation, but are most often used as literals: 
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equivalent ly, by being assigned a value by NARG, NCHR, EXT 
(see below), or by being used in the increment list of a RPT 
or CRPT statement). This latter sort of symbol is called 
equated . 

Labels: If a symbol appears in the label field of an 

instruction (or in the label field of some directives) 
then it is defined with the current value of the location 
counter (rfactor=l) . If the symbol is already defined, 
either as a label or as an equated symbol, the error 
message '(Symbol) REDEFINED ' is typed and the old 
definition is completely replaced by the new one. 

Equated symbols: These symbols are usually defined by EQU, 

getting the value of the expression in the operand field 
of the EQU directive. This expression must be defined 
and have an rf actor in the range [-15,151- If the symbol 
has been previously defined as a label, then the error 
message ' (Symbol) REDEFINED' is typed and the old definition 
is completely replaced by the new one; if the symbol has 
already been defined as an equated symbol, then no error 
message is given, and the old value and rfactor are 
replaced by the new ones. Thus, an equated symbol can be 
defined over and over again, getting a new value each time. 

A defined symbol is always local, and may also be external. 
If a symbol in package A is to be referred to from package B, 
it must be declared external in package A. This is done in 
one of the following ways: 

Declared external by $: If a label or equated symbol is 

preceded by a $ when it is defined, then it is declared external. 

$LABEL1 LDA ALPHA 

LABEL2 STA BETA LABEL2 IS LOCAL ONLY 

$GAMMA EQU DELTA 
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Declared external by the EXT directive: There are two cases: 

i) EXT has no operand: The symbol in the label field is declared 

external; it may have already been declared external or may 

even have a $ preceding it. -v 

ii) EXT has an operand: This case is treated exactly like the 

case: $label EQU operand. 

Certain symbols are pre-defined in NARP, i.e., they already 

have values when an assembly begins and need not be defined by 

the programmer: 

:ZERO: This is a relocatable zero (i.e., value = 0, rf actor = 1). 

:LC: This symbol is initially zero (rfactor=l) and remains 

so until the END directive is encountered and all literals 

are output, at which time it gets the value of the location 

counter. See the description of FREEZE for a discussion 

of the use of this symbol. 

* Syntactically this is not a symbol, but semantically 

it acts like one. At any given moment, * has the value 

of the location counter (rfactor=l), and can thus be used 

to avoid creating a lot of local labels. 

Thus CIA; LDX LENGTH 

LOOP STA TABLE, 2; BRX LOOP 

can be written as 

CLA; LDX LENGTH; STA TABLE, 2; BRX *-l 

If a given symbol is referred to in a program, but is not 
defined when the END directive is encountered then it is assumed 
that this symbol is defined as external in some other package. 
Whether this is the case cannot be determined until the various 
packages have been loaded by DDT. Such symbols are called 
"undefined symbols" or "external symbol references." It is 
possible to perform arithmetic upon them (e.g., LDA UNDEF+l) ; v 
an expression in post- fix Polish form will be transmitted to DDT. 
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2*5 Expressions and literals 

Loosely speaking, an expression is a sequence of constants 
and symbols cbnnected by operators. Examples: 
100-2*ABC/ [ALPHA+BETA] 
GAMMA 
F>=Q 

Following is the formal description (in Backus normal form) 
of a NARP expression: 

<primary> : : =<number> |<string constant> |<symbol> | * | [<expr> ] 

<expr>: :=<primary>|<unary operator> <expr> j<expr> <binary operator> <expr> 

<expressiori>: :=<expr>|<literal operator> <expr> 

<binary operator>: :=t |*|/ 1 + |-|<|<=>| = |#|>=|> |&| ! \% 
<unary operator> : : =+ | - j® 
<literal operator>::= =» 

Notice that the literal operator is rather special, only 
being allowed to appear once in a given expression, and only 
as the first character of the expression. Literals are 
discussed in greater detail below. 

The value of an expression is obtained by applying the 
operators to the values of the constants and symbols, evaluating 
from left to right except when this order is interrupted by the 
precedence of the operators or by square brackets* ([,]); the 
result is interpreted as a 2^-bit signed integer. The following 
table describes the various operators and lists their precedences 
(the higher the precedence, the tighter the operator binds its 
operands ) : 



C 
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Operator 



Precedence 



Comment 



t 


6 


exponentiation; exponent must be > 


#• 


5 


multiplication 


/ 


5 


integer division 


+ (u) 


U 


unary plus 


- (u) 


U 


negation (arithmetic) 


+ 


U 


addition 


- 


1+ 


subtraction 


< 


3 


less than 


<= 


3 


less than or equal to result of operati 


ss 


3 


equal to 


_ if relation is 


# 


3 


not equal to 


otherwise 1 


> = 


3 


greater than or equal to 




> 


3 


greater than «" 




#(u) 


2 


logical not 




& 


1 


logical and 


logical operation 


» 





logical or j> 


applied to all 


i 





logical exclusive or j 


2k bits 



false, 



The rfactor of an expression is computed at the same time 
the value is computed. There are constraints, however, on the 
rf actors of the operands of certain operators, as shown in the 
table below: (Note: Rl is a symbol with an rfactor of 1, R2 
is a symbol with an rfactor of 2). 





relocation factor(s) 


relocation factor 




operator 


of operand(s) 


of result 


examples 


t 






2tU=l6, 
Rltl( error) 


& ! 

7. 


all operands absolute 


absolute 


7&3=3, 
6&Rl(error) 


/ 






V2=2, 
Rl/l(error) 


# 


at least one rfactor 


found by multi- 


3*R2 has 




must be absolute, the 


plying the value 


rfactor of 6, 




other is arbitrary 


of the absolute 
operand times the 
rfactor of the 
other operand 


Rl*Rl( error) 


< <= = 


arbitrary relocation 




R1=R1 is true 


#>=> 


factors, but must be 
equal 


absolute 


R2>Rl(error) 


+ 




found by applying 


R1+R2 has 


(unary and 
binary) 


arbitrary rf actors 


operator to the 
relocation factors 
of the operands 


relocation 
factor of 3 



o 
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The final rfactor of an expression must be in the range 
[-8191, 8191]. 

If an expression contains an undefined symbol or if it is a 
literal, then the entire expression is undefined. 

Although a literal is a special kind of expression, it is 
often convenient to think of it as a quite separate entity. The 
use of literals is discussed below. 



o 
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Programmers frequently write such things as 

LDA FIVE 

where FIVE is the name of a cell containing the constant 5. The 
programmer must remember to include the datum FIVE in his program 
somewhere. This can be avoided by the use of a literal. 

LDA =5 

will automatically produce a location containing the correct 

constant in the program. Such a construct is called a literal. 

When a literal is encountered, the assembler first evaluates the 

expression and looks up its value in a table of literals constructed 

for each subprogram. If it is not found in the table, the value 

is placed there. In any case the literal itself is replaced by 

the location of its value in the literal table. At the end of 

assembly the literal table is placed after the sub-program. 

The following are examples of literals: 

=10 =4B6 =ABC*20-DEF/12 ='HELP' 

=2>AB (This is a conditional literal. Its value will 
be 1 or depending on whether 2>AB at assembly 
time. ) 

Some programmers tend to forget that the literal table 

follows the subprogram. This could be harmful if the program 

ended with the declaration of a large array using the statement 

ARRAY BSS 1 

It is not strictly correct to do this, but some programmers 

attempt it anyway on the theory that all they want to do is to 

name the first cell of the array. The above statement will do 

that, of course, but only one cell will be reserved for the 

array. If any literals were used in the subprogram, they would 

be placed in the following cells which now fall into the array. 

This is, of course, an error. Other than this exception, the 

programmers need not concern himself with the locations of the 

literals . 



•i 



o 
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3-0 Instructions 



There are three different syntactical forms of instruction 
statements, depending on the class of the instruction in the 
opcode field: (in the following, syntactical elements enclosed 
in square brackets are optional; they may or may not be present.) 



class 
class 1 
class 2 



[[$]label] opcode[*] [ operand [, tag] [comment]] 

[[$]label] opcode[*] [comment] 

[[$]label] opcbde[*] operand[,tag] [comment] 



o 



Each of the syntactical elements is discussed below: 

$ : A label preceded by a dollar sign is declared external 
(see section 2.4). 

label : The label is defined with the current value of the 
location counter (r f actor =l). 

opcode : The opcode must be either an instruction which is 

already defined or a number. If it is a number, then 
the value (mod 2 y ) of the number is placed in b0-b8 
(bit through bit 8) of the instruction, and it is 
treated as a class opcode (i.e., operand optional). 

* : If an asterisk follows immediately after the opcode 
then b9 (the indirect bit) of the instruction is set. 

operand: The operand is an expression which may or may not be 

defined and which has any rfactor. The expression may 
be preceded by '/' or '*"' ( or both in any order); 
these characters cause the following bits to be set: 
/ bl (index bit) 
«- b9 (indirect bit) 
Thus: 



LDA /VECTOR 
STA ^-POINTER 
LDA «-/COMPLX 



is the same as 
is the same as 
is the same as 



EDA VECTOR, 2 
STA* POINTER 
LDA* COMPLX,2 



o 



c 



c 



c 
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tag : The tag is an expression which must be defined and 
absolute. Its value (mod 2 J ) is placed in b0-b2 of 
the instruction. 

comment: The comment does not affect the instruction generated; n 
it may be listed. 

In addition to its class, a given opcode is designated as 
being either a shift instruction or a non-shift instruction. 
This has nothing to do with whether the action of the instruction 
involves shifting, but is simply a way of distinguishing between 

two kinds of instructions. For non-shift instructions, operands 

lU 
are computed mod 2 , while for shift instructions there are two 

possibilities: 

a) If the indirect bit is set by '*' or '«-', then the value 
of the opcode is trimmed so that bl0-b23 are zero, and 
then the instruction is treated as if it were a non- 
shift instruction. 

b) If the indirect bit is not set as above, then the 

9 
operand is computed mod 2^; it must be defined and 

absolute . ' 



o 
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4.0 Directives 



There are many directives in NARP; although some of them are 
similar, each in general has its own syntax. Following is a 
concise summary: 



Class 



Directive Use or Function 



Mnemonic for instructions: COPY 



Mnemonic for RCH 



Section 
4.4 



Data generation 



DATA 
ASC 

TEXT 



Generate data 4.5 

Generate text 

(3 charactersper word) 4.1 

Generate text (4 

characters per word) 4.23 



Value declaration 



C 



EQU 

EXT 

NARG 
KCHR 
OPD 
POPD 



Equate a symbol to 

a value 4.9 
Define a symbol as 

external 4 . 10 

Number of arguments 5 -5 

Number of characters 5 »5 

Define an opcode 4.17 
Define a programmed 

operator 4 . 19 



Assembler control 



C 



BES Block ending symbol 4.2 
BSS Block starting symbol 4.3 
END End of assembly 4.8 
DEC Interpret integers 

as decimal 4.6 

OCT Interpret integers 

as octal 4.16 

FRGT Do not output a 

specific symbol 4.12 
FRGTOP Suppress output 

of opcode 4.12? 

IDENT Identification of 

a package 4.13 
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Class 



Directive . Use or Function Section 

DELSYM Do not output any 

symbols 4.7 

RELORG Assemble relative 

with absolute origin 4.20 

RETREL ' Return to relocatable 

assembly 4.22 

FREEZE Preserve symbols, 

opcodes, and macros 4.11 



\ C 



Output and listing 
control 


: LIST 


Set listing controls 


4. Ik 




NOLIST 


Reset listing controls 


4.15 




PAGE 


Begin a new page on 
the listing 


4.18 




REM 


Type out remark 


4.21 


Conditional assembly 
and macros 


: IF 


Begin if body 


5.1 




ELSF 


Alternative if body 


5-1 




ELSE 


Alternative if body 


5-1 




ENDF 


End if body 


5-1 




RPT 


Begin repeat body 


5.2 




CRPT 


Begin conditional 
repeat body 


5-2 




ENDR 


End repeat body 


5.2 




MACRO 


Begin macro body 


5.4 


i 


LMACRO 


Alternative to MACRO 


5-4 




ENDM 


End macro body 


5-4 



In the remainder of this section, all directives listed 
above except for those associated with conditional assembly and 
macros are described. 



O 
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Ij-.l ASC Generate text (3 characters per word ) 

[[$]label] ASC string [comment] 

This directive creates a string of 8-bit characters stored 
3 to a word. The string starts in the leftmost character of a 
word and takes up as many words as needed; if the last word is 
not filled up completely with characters from the string, then 
the right end of the word is filled out with blanks. If a label 
appears, its value is the address of the first word of the 
string. The syntactical element "string" is usually any 
sequence of characters (not containing a single quote) surrounded 
by single quotes. However, the first character encountered 
after *ASC* is used as the string delimiter (of course, blanks 
and semi-colons cannot be used as string delimiters). 



Examples : 

ASC 'NO SINGLE QUOTES, HERE IS A SEMI-COLON:;' 
$ALFHA ASC $HERE IS A SINGLE QUOTE: »$ 



h-k 
k . 2 BES Block ending symbol 
[[$]label] BES expression [comment] \ 



•/ 



The location counter is incremented by the value of the 
expression in the operand field and then the label (if present) 
is given the new value of the location counter. Thus, in 
effect, a block of words is reserved and the label addresses 
the first word after the block. The expression must be defined 
and absolute. This directive is most often used in conjunction 
with the BRX instruction, as in the following loop for adding 
together the elements of an array: 

LDX — LENGTH; CIA; ADD ARRAY, 2 
BRX *-l; STA RESULT; HLT 
ARRAY BES LENGTH 
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f^ ^.3 BSS Block starting symbol 

[[$]label] BSS expression .[comment] 

This directive does exactly the same thing as BES except that \ t 
the label (if present) is defined before the location counter * 

is changed. Thus, the label addresses the first word of the 
reserved block. It should be noted that the expression for both 
BES and BSS may have a negative value, in which case the location 
counter is decremented. 



A 


23 


Clear A 


B 


22 


Clear B 


AB 


21 


Copy (A) -* B 


BA 


20 


Copy (B) ->A 


BX 


19 


Copy (B) ->X 


XB 


18 


Copy (X) -» B 


E 


17 


Bits 15-23 (exponent part)' only 


AA 


16 


Copy (X) -* A 
Copy (A) ->X 


AX 


15 


N 


Ik 


Copy -(A) ~> A (negate A) 


X 


1 


Clear X 



To exchange the contents of the B and X registers, negate A, 
and only for hits 15-23 of all registers, one would write 
COPT BX,XB,N,E 






k-6 
^ COPY Mnemonic for RCH 

[[$] label] COPY s ,s 2 ,s , ... [comment] 

(where s, are symbols from a special set associated with the 
COPY directive) 

The COPY directive produces an RCH instruction. It takes 
in its operand field a series of special symbols, each standing 
for a bit in the address field of the instruction. The bits 
selected by a given choice of symbols are merged together to 
form the address. For example, instead of using the instruction 
CAB (0l+6000CJ+), one could write COPY AB. The special symbol 
AB has the value OOOOOOOU. 

The advantage of the directive is that unusual combinations 
of bits in the address field — those for which there exist 
normally no operation codes — may be created quite naturally. 

The special symbols are mnemonics for the functions of the f*\ 

various bits. Moreover, these symbols have this special meaning 
only when used with this directive; there is no restriction on 
their use either as symbols or opcodes elsewhere in a program. 
The symbols are; 

Symbol Bit Function 



O 



k-7 

U.5 DATA Generate data 

[[$]label] DATA e 1 ,e 2 ,e-,... [comment] 

The DATA directive is used to produce data in programs. , 

Each expression in the operand field is evaluated and the 2l»-bit * 
values assigned to increasing memory locations. One or more 
expressions may be present. The label is assigned to the 
location of the first expression. The effect of this directive 
is to create a list of data, the first word of which may be 
labeled. 

Since the expressions are not restricted in any way, any 
type of data can be created with this directive. For example: 

DATA 100,-217B,STABT,AB*2/DEF, 'NUTS • ,5 
creates six words. 



c 
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4.6 EEC Interpret integers as decimal 

a ^ 

EEC [comment] ^ 

The radix for integers is set to ten so that all following 
integers (except those with a "R- suffix) are interpreted as *' 

decimal, "hen an assembly begins the radix is initialized to 
ten, so DEC need never be used -unless the OCT directive is used. 
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k.7 DELSYM Do not output any symbols 

DELSYM [comment] 

If DELSYM appears anywhere in a program being assembled, 
the symbol table and opcode definitions will not be output 
by NARP when the END directive is encountered. The main purpose 
of this directive is to shorten the object code generated by 
the assembler, especially when the symbols are not going to 
be needed later by DDT. 



G 
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k.8 END End of assembly 
EOT) [comment] 

When this directive is encountered the assembly terminates. 
If the LIST directive has been used then various information may 
be listed, for example undefined symbols. 



O 



c 



o 
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k.S EQU Equate a symbol to a value 

[$] symbol EQU expression [comment] 

The symbol is defined with the value of the expression; if 
the symbol is already defined, its value and rfactor are changed. 
The expression must be defined and must have an rfactor in the 
range [-15,15]. If the symbol has been declared external before 
or if it has been forgotten (using FRGT) then EQU preserves this 
information. Thus 



$ALPHA EQU h 
ALPHA EQU 3 



will cause ALPHA to be declared external but with a value of 
three at the end of the assembly (provided ALPHA is not changed 
again before the END directive). See section 2.k for more 
discussion of EQU. 



11 



c 
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4.10 EXT Define a symbol as external 

[$] symbol EXT [expression [comment]] 

This directive is used to declare symbols as external. See 
section 2.4 for a discussion of the various cases. 
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4.11 FREEZE Preserve symbols, opcodes, and macros 

FREEZE [comment] 

Sometimes subprograms share definitions of symbols, opcodes, 
and macros. It is possible to cause the assembler to take note 
of the current contents of its symbol and opcode tables and the 
currently defined macros and include them in future assemblies, 
eliminating the need for including copies of this information 
in every subprogram's source language. 

When the FREEZE directive is used, the current table 
boundaries for symbols and opcodes and the storage area for macros 
is noted and saved away for later use. These tables may then 
continue to expand during the current assembly. (A separate 
subprogram may be used to make these definitions; it will then 
end with FREEZE; END.) The next assembly may then be started 
with the table boundaries returned to what they were when FREEZE 
was last executed. This is done by entering the assembler 
at its "continue" entry point, i.e., by typing 

^CONTINUE NARP. 
Note that the assembler cannot be released (i.e., another 
subsystem like QED or DDT cannot be used) without losing the 
frozen information. 

In conjunction with the FREEZE directive, the predefined 

symbol :LC: is useful, especially when writing large 

re-entrant programs. Following is a three-package program 

using FREEZE and :LC:. 

PI 3DENT 

definitions of macros, opcodes, and global equated 

symbols> 
<definition of working storage (i.e., read-write 

memory )> 
FREEZE 
END 

P2 IDENT 

BSS :LC:-:ZERO: 

<read-only code> 

END 
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r 



Pl> idem: 



»v 



BSS :LC:-:ZERO: 
<read-only code> 

END \ 

The FREEZE directive at the end of PI preserves all the 
definitions in this package so they can be referenced in packages 
P2 amd P3. By including the definitions of all the working storage 
cells in the preserved definitions, these symbols need not be 
declared as external. Also, it makes "external" arithmetic on these 
symbols possible in P2 and P3, and it reduces the number of 
undefined symbols printed at the end of an assembly. Packages 
P2 and ?3 start with the rather -Deculiar looking BSS in order 
to set the location counter so that references between the 
packages will be correct. This is the main puroose of :LC:, 
it saves the final value of the location counter from the 
previous package for use by the current package. In order for 
this scheme to work, all three packages must be loaded at the 
same location, usually for large re-entrant programs. 

Assume ALPHA is a symbol defined in PI. Unless some 
special action is taken, ALPHA will be output to DDT three times, 
once at the end of PI, once at the end of P2, and once at the end 
of P3. To avoid this, all symbol and opcode definitions are 
marked after they have Tbeen output once so that they won't be 
output again. 



O 
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4.12 FRGT Do not output a specific symbol 
FRGT s ,Sp, ... [comment] 



\. 



The symbols s. (which must have been previously defined) '«" 

are not output to DDT. FRGT is especially useful in situations 
where symbols have been used in macro expansions or conditional 
assemblies, and have meaning only at assembly time. When DDT 
is later used, memory locations are sometimes printed out in 
terms of these meaningless symbols. It is desirable to be 
able to keep these symbols from being delivered to DDT, hence 
the FRGT directive. 



» • 



4.125 FRGTOP Forget selected opcodes 
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FRGTOP s , s , . . . [ comment ] 

The s. must be opcodes. The specified opcodes are marked * 

as forgotten and will not be output to DDT. Since DDT knows 
in advance about the standard instruction set (e.g., LDA, BRS, 
CIO), FRGTOP otl\ such opcodes has no effect. It follows that 
the chief use of FRGTOP will be to suppress output of opcodes 
generated by OPD and POPD. 

FRGTOP does not take a label. 



o 
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4.13 IDEMT Identification of a package 

symbol IDEM? [comment] 

The symbol in the label field is delivered to DDT as a 
special identification record. DDT uses the IDENT name in con- 
junction with its treatment of local symbols: in the event of 
a name conflict between local symbols in two different subprograms, 
DDT resolves the ambiguity by allowing the user to concatenate 
the preceding IDENT name with the symbol in question. Also, 
during an assembly the first six characters of the symbol followed 
by the word * IDENT ' are typed on the teletype to show the user 
what package is being assembled. The progress of an assembly- 
can be followed by placing IDENT' s at various points in the 
package . 
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4.135 LIBEXT Specify library symbol 
Symbol LIBEXT [comment] 

This directive causes "symbol" to be output to the binary 
file, marked as a special "library- symbol." The resulting 
binary file must then be mauled by a library-making program 
before it will be intelligible to the loader in DDT. 

The library-maker takes a binary file and moves all of the 
library-symbols to the beginning of the program, and puts the 
result on % file as a "library-program." When a "library- file" 
(which contains one or more library-programs) is loaded into 
DDT, the loader scans the list of library symbols before each 
library-program. If any of them is currently undefined (i.e., 
referenced but not defined in previously loaded programs), the 
associated library-program is loaded normally; otherwise, it 
is not loaded. 

For example, one could write a sine and cosine library program: 
O SIN LIBEXT 

*SINE ROUTINE: ANGLE IN RADIANS 
$SIN ZRO SINX 

(sine routine code) 

COS LIBEXT 

*COSINE ROUTINE: ANGLE IN RADIANS 
$COS ZRO COSX 

(cosine routine code) 

END 

Assemble it with NARP and use the library-maker to put it on 
a library-file as a library- program. Then, if either "SIN" 
or "COS" is undefined when the library-file is loaded, both 
the sine and cosine subroutines will be loaded, and the symbols 
"SIN" and "COS" defined as the entry points of the routines 
(respectively), (if one desired to have them load independently, 
each subroutine could be made into a separate library-program.) 

c o 
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(Note: The library-program is loaded normally once the decision 

to load it has been made; thus, undefined library- symbols will 

only be defined and linked in previously- loaded programs if they t, 

are defined and made external in the library-program in the 

usual fashion (as in the example).) 



c 
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^• lif LIST Set listing controls 



^•15 NOLIST Reset listing controls 

r LIST ~\ 
NOLIST 



;i 'V - 



[ comment ] ] 



There are various booleans which control the format in 
which statements are listed (certain fields and/ or certain 
kinds of statements may be suppressed, or listed selectively) 
The user is allowed to set (or reset) these booleans via the 
LIST (or NOLIST) command. Each of the s. may be one of the 
following special symbols: 



s. Set (or 

X 


reset) 


What is (or is not) listed 


LCT 




the current value of the location 
counter, in octal 


SLOT 




the symbolic address of the current 
value of the location counter 


VAL 




the value of the statement, if it is 
one of the directives: EQU, NCHR, 
KARG, IF, ELSF. (in octal) 


SRC 




the symbolic source code 


COM 




the comment field of a statement, a 
comment statement 


CALL 




macro and RPT calls 


DEF 




MACRO and RPT definitions 


EXP 




macro and RPT expansions 


SKIP 




the skipped parts of an IF statement 


EXT 




external symbol references (at the 
end of the assembly 







— .—IMMIIWT"— " 
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In addition, s may be "ALL", which will cause all of the 
booleans in the table to be set (or reset). 

If a LIST (or NOLIST) directive is encountered for which 
no arguments (s.) have been specified, HARP will begin (or 
cease) listing statements on the LISTING FILE (the teletype, 
in case no other listing file is specified when the assembly- 
is begun) according to the current settings of the listing 
booleans. Including "GO" among the arguments for a LIST 
(or NOLIST) will have the same effect. 

When NARP is called, the listing booleans are initialized 
as follows: 

Set: LCT, VAL, SRC, COM, CALL, DEF, EXP, EXT 
RESET: SLCT, SKIP 

and NARP is in its "no list" state, i.e., listing will not 

be started unless (and until) the program initiates it with a 

LIST directive. 

Examples of the LIST directive: 

NOLIST ALL Resets all format booleans 

LIST SRC, GO Sets SRC boolean and starts listing 

(only the source code will be listed) 

Examples of listing format; 

LCT SLCT VAL SRC COM 




00117 (A) 3 A EQU 6/2 (SET A) 
00117 (HERE) HERE LDA A*B,2 
00120 (HERE+l) 
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V ,' 4.l6 OCT Interpret integers as octal 

OCT [comment] 

The radix for integers is set to eight so that all following 
integers (except those with a D- suffix) are interpreted as octal. 






O 
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k.YJ OPD Define an opcode 

symbol OPD value [, class [, shift kludge]] 

The symbol in the label field is defined as an opcode with '• 
a value equal to the first expression in the operand field. All 
expressions in the operand field must be defined and absolute; if 
an optional expression does not appear then the value is assumed. 

value : computed mod 2 (see important note below; 

class : must have a value of 0,1, or 2: 

- the opcode may or may not have 

an operand 

1 - the oiDCode does not take an 

operand 

2 - the opcode requires an operand 

shift kludge: must have a value of or 1: 

- non- shift instruction 

(see section 3) 

1 - shift instruction (see section 3) 

Note: Although an opcode that takes operands can be defined with 
bits bl0-b23 set, the user must be careful of what he is doing. 
In particular, if such an opcode appears in an instruction which 
contains a literal or an undefined value then bits bl0-b23 of the 
opcode are set to f.ero. 

If the symbol in the label field is already defined as an 
opcode then the old definition is lost. 
Examples : 

055B5,2 

0U60000IB, 1 

0662Sh,2,l 

020B5 



ADD 


OPD 


CIA 


OPD 


RCY 


OPD 


NOP 


OPD 



V 
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U.19 POFD Define a programmed operator 



symbol POPD value [, class [, shift kludge]] 

This directive does exactly what OPD does with one addition: 
The instruction BRU* is placed in the memory location whose 
address is in b2-b8 of the value given to the symbol (this 
address must be in the range [100B, 177B]). Thus 



MIN 


POPD 


100B5,2 


LMIN 


SKG* 







BRR 







IDA* 







BRR 






THE CALL 'MIN ALPHA' WILL 
CAUSE THE MINIMUM OP 
A -REG AND ALPHA TO BE 
LEFT IN A-REG. 



will cause BRU LMIN to be loaded in word 100B. 



o 
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4.20 RELORG Assemble relative with absolute origin 

RELORG expression [comment] 

On occasion it is desirable to assemble in the midst of 
otherwise normal program a batch of code which, although loaded 
in oere in one position, is destined to run from another position 
im memory. (It will first be moved there in a block.) This is 
particularly useful when preparing program overlays. TTie 
expression in the operand field (which must be absolute and 
defined) denotes an origin in memory. The following occurs when 
the directive is encountered: 

a.) The current value of the location counter is saved, and 

im its place is put the absolute origin (i.e., the 

value of the expression). This fact is not revealed 

to DHT, however, so during loading the next instruction 

assembled will be placed in the next memory cell available 

as if nothing had happened. 
b.) The mode of assembly is switched to absolute, i.e., aH 

symbols defined in terms of the location counter will 

be absolute. 
It is possible to restore normal relocatable assembly (see section 
4.22). 

As an example of the use of RELORG, consider a program 
beginning with RELORG 300B. The assembler's output represents 
an absolute program whose origin is 0Q300g, but which can be 
loaded anywhere using DE3? in the usual fashion. Of course, 
before executing the program it will be necessary to move it to 
location OO3.OO0. 

As another example, consider the following use of RELORG and 
RETREL: 

<normal relocatable pro«ram> 

RELORG 10CB 

<absolute program with origin at 10GB> 

RELORG 200B 

<ab solute program with origin at 200B> 



1, 



c 



RETREL 

<normal relocatable program> 

RELORG 300B 

<absolute program with origin at 30GB> 

EM) 
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If. 21 REM Type out remark 

REM text 

This directive causes the text in its operand and comment 
fields to be typed out either on the teletype or whatever file 
has been designated as the text file (see section 6.2). This 
typeout occurs regardless of what listing controls are set. The 
directive may be used for a variety of purposes: It may inform 
the user of the progress of assembly; it may give him instructions 
on what to do next (this might be especially nice for complicated 
assemblies); it might announce the last date the source language 
was updated; or it might be used within complex macros to 
show which argument substrings have been created during 
expansion of a highly nested macro (for debugging purposes). 






o 
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C / ^' 22 RETREL Return to relocatable assembly 

RETREL [comment] 

^his directive is used when it is desired to return to 
relocatable assembly after having done a RELORG. It is not 
necessary to use RETREL unless one desires more relocatable 
program. An example of the use of RETREL is shown in section 
if. 20. The effects of RETREL are 

a.) to restore the location counter to the value it would 

have had if the RELORG (s) had never appeared, and 
b.) to return the assembly to relocatable mode so that 
labels are no longer absolute. 
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if. 23 TEXT Generate text (k character per word ) 

[[$] label] TEXT string [comment] 

This directive is exactly the same as ASC (see section k.l) 
except that characters are taken as six bits each and are stored 
four to a word. 
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5-0 Conditional assemblies and macro; 



5.1 IF, ELSF, ELSE, and ENDF 



If statements 



It is frequently desirable to permit the assembler either to 
assemble or to skip blocks of statements, depending on the value of 
an expression at assembly time. This is primarily what is meant 
by conditional assembly . In NARP, conditional assembly is done 
by using either an if statement or a repeat statement - 

The format of an if statement is 



IF expression 

< if body > 

ENDF [comment] 



[ comment ] 



The if body is any block of NARP statements, in particular, it may 
contain directives of the form 



and 



ELSF expression [comment] 
ELSE [comment] 



If the operand of IF is true, then the block of code up to the 
matching ENDF (or ELSF or ELSE) is processed; otherwise, it is 
skipped. The values for true and false are: 

true : value of expression > 
false : value of expression < 



Examples: 



IF 
IDA 
STA 
ENDF 

IF 
LDA 
STA 
ENDF 



]>0 

ALPHA 
BETA 



} — 



P 

GAMMA 1 

DELTA J Skipped 
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Often there are more than two alternatives, so the ELSP 
directive is used in the if body. When ELSF is encountered while 
skipping a block of statements, its operand is evaluated (just 
as for IF) to decide whether to process the block following the 
ELSF. 



Examples : 






IF 


> 1 




LDA 


ALPHA 


skipped 


ELSF 


1 > 




LDA 


BETA 


processed 


ENDF 






IF 


> 1 




LDA 


ALPHA 


skipped 


ELSF 


> 1 




LDA 


BETA 


skipped 


ENDF 






IF 


1> 




LDA 


ALPHA 


processed 


ELSF 


1 > 




LDA 


BETA 


skipped 


ENDF 






IF 


> 1 




LDA 


ALPHA 


skipped 


ELSF 


1 > 




LDA 


BETA 


processed 


ELSF 


1 > 




LDA 


GAMMA 


skipped 


ENDF 







From the last two examples above it should be clear that either 
no blocks are processed or precisely one is; thus, as soon as one 
block is processed, all following blocks are skipped regardless 
of whether the ELSF expressions are true. 
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An ELSE directive is equivalent to an ELSP directive with a 
true expression. 

Example : 



IF > 1 

IDA ALPHA skipped 

ELSE 

LDA BETA processed 

EEDF 



As a more general example, consider the following: 

IF el 

< body 1 > 
ELSF e2 

< body 2 > 
ELSF e3 

< body 3 > 
ELSE 

< body h > 
ENDF 

There are four possibilities: 

a) el > : process body 1, skip the other three 

b) el < 0, e2 > : process body 2, skip the other three 

c) el < 0, e2 < 0, 

e3 > : process body 3> skip the other three 

d) el < 0, e2 < 0, 

e3 < : process body h, skip the other three 

The bodies between the IF, ELSF, ELSE, and ENDF directives 
may contain arbitrary KARP statements, in particular they may 
contain other if statements. This nesting of if statements may 
go to any level. 

When evaluating the expression in the operand field of IF or 
ELSF, all undefined symbols are treated as if they were defined with 
value -1. These expressions must be absolute. 
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DATA 





DATA 





DATA 





DATA 






An increment list has the form (s=el[,e2] ). . , (s=el[ ,e2] ) 
where s stands for a symbol and el and e2 denote expressions 
(which must be absolute; undefined symbols are treated as if they 
were defined with the value -l). Before the repeat body is processed 
for the first time, each symbol in the list is given the value of 
its associated el. Thereafter, each symbol is incremented by the 
value of its associated e2 just before the repeat body is processed. 
If e2 is missing, the value 1 is assumed. There is no limit on 
the number of elements that may appear in an increment list. 
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5.2 RPT, CRPT, and ENDR Repeat statements 

A repeat statement is a means of processing the same text many 
times. The format is *< 

[[$]label] RPT express ion[, increment list] [comment] 
< repeat body > 
ENDR [comment] 

The value of the RPT operand (which must be defined and absolute) 

determines how many times the repeat body will be processed, while 

the increment list (described below) is a mechanism to allow the 

values of various symbols to be changed each time the repeat body 

is processed. 

Example : 

ABC RPT k 

DATA 

ENDR 

This is equivalent to 
ABC 
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L-' Example: Q 



G 



r/" 



RPT 3,(l=4)(J=0,-l) 

DATA. I 

DATA. J*I+1 
ENDR 



This results in code equivalent to the following: 



DATA 


k 




DATA 


0*1* +1 


=1 


DATA 


5 




DATA 


-1*5+1 


=-4 


DATA 


6 




DATA 


-2*6+1 


=-11 



There is another format for RPT: 
[[$]label] RPT (s=el[ ,e2],e3)[ increment list] [comment] 
In this case, the number of times the repeat body is processed is 
determined by the construct (s=el[,e2],e3). This is the same as 
an increment list except that it includes a third expression 
(which must be absolute; all undefined symbols are treated as if 
they were defined with the value -1), namely a bound on the value 
of the symbol. As soon as the bound is passed, processing of the 
repeat body stops. In the example above, the same effect could 
have been achieved by writing the head of the repeat statement as 

RPT (J=0,-l,-2)(l=4) 
or as 

RPT (I=U,6)(J=0,-1) 

Note that the bound does not have to be positive or greater than 
the initial value of the symbol being incremented; the algorithm 
for determining when the bound has been passed is given below. 

Occasionally one wishes to perform an indefinite number of 
repeats, terminating on an obscure condition determined in the 
course of the repeat operation. The conditional repeat directive, 
CRPT, serves this function. Its effect is like that of RPT (and 
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its repeat body is also closed off with an ENDR) except that instead 
of giving a number of repeats, its associated expression is evaluated 
just prior to each processing of the repeat body to determine 
whether to process the block. As for IF, > means true, < means 
false; the expression must be defined and absolute each time it is 
evaluated. The form is 

[[$]label] CRPT expression [, increment list] [comment] 

For example, one may write 

CRPT X>Y 
or 

CRPT STOP, (X=l,2)(Y=-3) 

Note that the statement 

CRPT 10 
will cause an infinite number of repeats. 

The following flowcharts describe precisely the actions of 
the various repeat options: 

RPT express ion [, increment list] 



skip the whole 
repeat block 





yes 



count := value of expression 



no 




i initialize symbols in increment 
-*j list; evaluate all e2 expressions 



T 



process the repeat body 



iz_ 



increment the symbols in 
the increment list 



O&L. 



count:=s count -1 



The el and e2 expressions 
are evaluated just once. 



yes 




jTcount =01 



no 



o 
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RPT (S=«ll^e2],e3)[i ncremen ^ ±± & ^] 




3:- el 



yes 




evaluate e2 and e3j 
initialize symbols in |«c* 
increment list; evaluate 
all e2 expressions. 



( S-e 3 ) *s ign ( e2>0^) ^_ 



*ie : ,kfo 



process the repeat block 



X- 



increment the symbols in 
the increment list 



ak_ 



S:= S+e2 



All expressions are 
evaluated jast once, 



O 
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CRPT 



expression [, increment list] 




initialize symbols in increment 
list; evaluate all e2 expressions: 



All el and e2 expressions 
are evaluated just once 



no 




J2_ 



evaluate expression it 




value expression > 



E> 



yes 



process the repeat block 



This expression is eval- 
uated over and over again 
and, of course, the values 
of the symbols in this 
expression may change from 
one evaluation to the next. 




The contents of a repeat body may contain any HAEP code, in 
particular it may contain other repeat statements; the nesting of 
repeat statements may go to any level. 
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5.3 Introduction to macros 

On the simplest level a macro name may be thought of as an 
abbreviation or shorthand notation for one or more assembly- 
language statements. In this respect it is like an opcode in that 
an opcode is the name of a machine command and a macro name is 
the name of a sequence of assembly language statements. 

The °k0 has an instruction for skipping if the contents of 

a specified location are negative, but there is no instruction 

for skipping if the accumulator is negative. The instruction 

SKA (skip if memory and the accumulator do not compare ones) will 

serve when used with a cell whose contents mask off all but the sign 

bit. The meaning of SKA when used with such an operand is "skip 

if A is positive". Thus a programmer writes 

SKA =UBT 

BRU NEGCAS NEGATIVE CASE 

However, it is more than likely the case that the programmer 

wants to skip if the accumulator is negative, ^hen he must write 

SKA =UBT 

BRU *+2 

BRU POSCAS POSITIVE CASE 

Both of these situations are awkward in terms of assembly language 

programming . 

But we have in effect just developed simple conventions for 

doing the operations SKAP and SKAW (skip if accumulator positive 

or negative). Define these operations as macros: 

SKAP MACRO 

SKA =1+B7 
EMJM 



SKAN MACRO 

SKA =UB7 
BRU *+2 

EEDM 

s-~ ^ Wow, more in keeping with the operations he had in mind, the — . 



o 
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Programmer may write 

A22 SKAN 

BRU POSCAS 

The advantages of being able to use SKA.P and SKA.N should be 
apparent. The amount of code written in the course of a program 
is reduced; this in itself tends to reduce errors. A greater 
advantage is that SKAP and SKAN are more indicative of the action 
that the programmer had in mind, so that programs written in this 
way tend to be easier to read. Note, incidentally, that a label 
may be used in conjunction with a macro. Labels used in this way 
are usually treated like labels on instructions; they are assigned 
the current value of the location counter. This will be discussed 
in more detail later. 

Before discussing more complicated uses of macros, some 
additional vocabulary should be established. A macro is an 
arbitrary sequence of assembly language statements together 
with a symbolic name . During assembly, the macro is stored in an 
area, of memory called the string storage . Macros are created 
(or, as is more frequently said, defined ) by giving a name and the 
associated sequence of statements. The name and the beginning 
of the sequence of statements are designated by the MACRO directive: 
name MACRO 



EHDM 
The end of the sequence of statements is indicated by the ENDM 
directive. 

Refer to figure 1. When the assembler encounters a MACRO 
directive, switch B is thrown to position 1 so that the macro 
is simply copied into the string storage; note that the assembler 
does no normal processing but simply copies the source language. 
When the EtTOM terminating the macro definition is encountered, 
switch B is put back to position and the assembler goes on 
processing as usual. 

It is possible that within a macro definition other definitions 
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Figure 1: Information Flow During Macro Processing 



SOURCE 
LANGUAGE 



BINARY 

MACHINE 

LANGUAGE 



7FT 



ASSEMBLER 




1 



© 1 



-«- 



STRING 
STORAGE 



A B 



1 

1 

1 1 



Effect 

normal assembly- 
macro definition 
macro expansion 
macro definition during 
macro expansion 
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may be embedded. The macro defining machinery counts the 
occurrences of the MACRO directive and matches them against the 
occurrences of ETOM. Thus switch B is actually placed back in 
position only when the EEDM matching the first MACRO is 
encountered. Therefore, MACRO and EKDM are opening and closing 
brackets around a segment of source language. Structures like 
the following are possible: 



name 1 


MACRO 


name 2 


MACRO 




name 3 


MACRO -t 
EKDM — 1 




name k 


MACRO-| 
ENEM-J 

EM5M 




name 5 


MACRO -j 

EMM— ' 
ENDM— * 



The utility of this structure will not be discussed here. Use 
of this feature of imbedded definitions should in fact be kept 
to a minimum since the implementation of this assembler is such 
that it uses large amounts of string storage in this case. What 
is important, however, is an understanding of when the various 
macros are defined. In particular, when name 1 is being defined, 
name 2, 3, etc., are not defined; they are merely copied into 
string storage. Wame2, for example, will not be defined until 
namel is expanded. (it should be noted that macros, like 
opcodes, may be redefined.) 

The use of a macro name in the opcode field of a statement 
is referred to as a call . The assembler, upon encountering a macro 
call, moves switch A to position 1 (see figure l). Input to the 
assembler from the original source file temporarily stops and comes 
fnstead from string storage. During this period the macro is said 
to be undergoing expansion . It is clear that a macro must be 
defined before it is called. 

An expanding macro may include other macro calls, and these, 
in turn, may call still others. In fact, macros may even call 
themselves; this is called recursion . Examples of the recursive 
use of macros are given later. When a new macro expansion begins 
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within a macro expansion, information about the progress of 
the current expansion is saved. Successive macro calls cause 
similar information to he saved. At the end of each expansion 
the information about each previous expansion is restored. When 
the final expansion terminates, switch A is placed back in 
position 0, and input is again taken from the source file. 

Now let us carry our example one step further. One might 
argue that the action of skipping is itself awkward. It might 
be preferable to write macros BRAP and BRAN (branch to specified 
location if contents of accumulator are positive or negative). 
How is one to do this? The location to which the branch should 
go is not known when the macro is defined, in fact, different 
locations will be used from call to call. The macro processor, 
therefore, must enable the programmer to provide some of the 
information for the macro expansion at call time . This is done 
by permitting dummy arguments in macro definitions to be replaced 
by arguments (i.e., arbitrary substrings) supplied at call time. 
Each dummy argument is referred to in the macro definition by a 
subscripted symbol. This symbol or dummy name is given in the 
operand field of the MACRO directive. 

Let us define the macro BRAP: 

BRAP MACRO LABEL 
SKAN 

BRU LABEL(l) 
ENDM 

When called by the statement 'BRAP POSCAS 1 , the macro will 

expand to 

SKA =UB7 
BRU *+2 
BRU POSCAS 

Note that BRAP was defined in terms of another macro, SKAN. Also 
note that as defined BRAP was intended to take only one argument; 
other macros may use more than one argument. 
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The macro CBE (compare and branch if equal) takes two 

arguments. The first argument is the location of a cell to be 

compared for equality with the accumulator; the second is a 

branch location in case of equality. The definition is 

CBE MACRO D 

SKE D(l) 

BRU *+2 

BRU D(2) 
EHDM 

When CBE is called by the statement 

CBE =*21B,EQL0C 
the statements generated will be 

SKE =21B 
BRU *+2 
BRU EQLOC 

Note that in the macro call, the arguments are separated by 
commas . 

The following sections describe macro definitions and 
calls in more detail. 
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5 A MACRO, LMACRO, and ENDM Macro definition 



name 



The form of a macro definition is: 
MACRO ■* 

or I [dummyC, generated, expression]] [comment] 
LMACROJ 



r 



V-. 



C 



where name , generated , and dummy are all symbols, and expression 
is an expression. 

LMACRO is completely equivalent to MACRO except that if 
name is defined as a macro with MACRO the construct 

label name arguments 

will automatically cause label to be defined as the current 
value of the location counter, whereas if name were defined 
with LMACRO this automatic definition of label would not 
occur. 

Some details of the definition 

If generated appears, it should not be the same symbol 
as dummy , and neither of them should be "MACRO", "LMACRO", or 
"ENDM. " 

If name is already defined as an opcode, the old definition 
is completely replaced by the new. 

If the MACRO (or LMACRO) directive has no operand, then 
name is defined as an opcode that takes no operands. Otherwise, 
name becomes an opcode that may or may not take an operand. 

Whole-line comments (lines beginning with *) in the macro 
body are not saved in string storage as part of the macro 
definition, but comments following instructions are. Thus, it 
behooves the programmer to avoid the latter, as they eat 
string storage. 



c> 



5-16 



When a macro body is placed in string storage, superfluous 
blanks are removed. Thus, any contiguous string of blanks is 
compressed to one blank with the following exceptions: 

a) Blanks enclosed in single quotes (') are not compressed. 

b) Blanks enclosed in double quotes (") are not compressed. 

c) Blanks enclosed in parentheses are not compressed. In 
this use, the nesting of parentheses is taken into 
account, but a parenthesis between single or double 
quotes is not considered as part of the nesting 
structure . 

In most cases the programmer need not worry about these 
conventions, although there are times when he may get pinched. 
For example, if 

ASC HAuxBH, 
appears in a macro definition, it will be expanded as 

ASC #A A B# 
To avoid such problems use 

ASC 'A^jB' 
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5A.1 Dummy arguments 

The dummy argument specified as an operand of the MACRO 
directive may appear anywhere in the macro body, followed by a 
subscript. At call time the subscript is evaluated and its value 
is used to select the appropriate argument supplied in the call. 
Before describing the various kinds of dummy arguments a few 
conventions are needed: 

a) In the following, "argument" will refer to the character 
string as given in the macro call after possible enclosing 
parentheses have been removed (see section 5«6 for the 
format of argument strings). 

b) The number of arguments supplied by the call is n (n>0). 

c) The number of characters in argument ei is n(ei). 

d) The structure ei for i an integer stands for an expression. 
(However, its value stands for some argument usually, so 
ei will be used somewhat ambiguously to stand for an 
expression or the value of an expression.) The first 
argument in a call is numbered 1. 

e) The dummy argument is assumed to be "D". 

With the above in mind, we consider the three forms of dummy 
arguments : 

1) D(el) 

This expands to argument el (which may be the null string), where 
< el < n. (If el = then D(el) expands to the label field of 
the macro call; see section 5>6.) 
Special notation: D() = D(l) 

2) D(el,e2) 

If el > e2 then this expands to the null string (range of values 
of el and e2 is arbitrary), otherwise, this expands to argument 
el through e2, where < el < e2 < n, with each argument enclosed 
in parentheses and a comma inserted between each argument. For 
example, D(3,3) = (D(3)). 
Special notation: D(,) = D(l,n) 

D(,el) = D(l,el) 

D(el, ) = D(el,n) 
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3) D(el$e2,e3) 
In all cases, < el < n must be true. If e2 > e3 then this 
expands to the null string (range of values of e2 and. e3 is \ 

arbitrary), otherwise, it expands to characters e2 through e3 
of argument el, counting the first character of an argument as 
character 1. If either e2 or e3 lies outside the argument, then 
the nearest boundary is chosen. To be more precise, before using 
e2 and e3 to select the piece of argument el that is desired, the 
following transformation is made: 

e2: = max (l,e2); e3:« max (l,e3); 

e2: = min (n(el), e2); e3:= min (n(el),e3); 

If argument el is the null string, then the dummy argument expands 
to the null string regardless of the values of e2 and e3. 
Special notations: 

D(el$,) = D(el$l, n(el)) = D(el) 

D(el$,e2) = D(el$l,e2) 

D(el$e2, ) = D(el$e2,n(el)) 

D(el$e2) = D(el$e2,e2) 

D(el$) = D(el$l) = D(el$l,l) 

In any of the six forms mentioned above, el may be missing; 

if so, 1 is assumed. E.g., D($) = D(l$l,l). 
A general rule which will help in remembering what the special 
notations mean is the following: "Whenever an expression is 
missing from a form, the value 1 is assumed unless the expression 
is missing from a place where an upper bound is expected (as in 
D(3, ) or D(3$2, ), in which case the largest 'reasonable' value is 
assumed." 

In any of the above three cases, if an expression which 
designates an argument is out of range, then an error message is 
typed and argument is taken. 
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Following is an example of the various forms of dummy 
arguments : 



Macro definition: 



XAMPLE 



MACRO 
D(2) 

ASC 

TEXT 

ASC 

ASC 

ENDM 



D 3 

DO.' 

«D(i2,10' 

•D(1$3,U) 

T D(2$-3,18) 



D(0) 
D(-3,-4) 



NULL STRING 



Macro call: 

BETA XAMPLE 



ALPHA , ADD , GAMMA , DELTA 



Macro expansion: 



BETA 



ADD 


ALPHA. BETA 


ASC 


"(CAMMA), (DELTA)' 


TEXT 


'(DELTA)* NULL STRING 


ASC 


'PH' 


ASC 


'ADD' 
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5-^.2 Generated symbols 

A macro should not, of cotrrse, have in its definition an 
instruction having a label. Successive calls of the macro would 
produce a multiply-defined symbol. Sometimes, however, it is 
convenient to put a label on an instruction within a macro. 
There are at least two ways of doing this. The first involves 
transmitting the label as a macro argument when it is called. 
This is most reasonable in many cases; it is in fact often 
desirable so that the programmer can control the label being 
defined and can refer to it elsewhere in the program. 

However, situations do arise in which the label is used 
purely for reasons local to the macro and will not be referred 
to elsewhere. In cases like this it is desirable to allow for 
the automatic creation of labels so that the programmer is freed 
from worrying about this task. This may be done by means of the 
generated symbol . 

A generated symbol name may be declared when a macro is 
defined, specifying the name and the maximum number of generated 
symbols which will be encountered during an expansion. These 
two items follow the dummy symbol name given in the MACRO directive 
(as shown in section 5 .k above) if the programmer wishes to use 
generated symbols in a macro. For example, 
MUMBLE MACRO D,G,U 
< macro body > 
ENBM 
might contain references to G(l), G(2), G(3), and G(U), these 
being individual generated symbols. 

With regard to generated symbols the macro expansion machinery 
operates in the following fashion: A generated symbol base value 
for each macro is initialized to zero at the beginning of assembly. 
As each generated symbol is encountered, the expression constituting 
its subscript is evaluated. This value is added to the base 
value, and the sum is produced as a string of digits concatenated 
to the generated symbol name; the first digit is always to 
reduce the likelihood of the generated symbol being identical to 
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a normal symbol defined elsewhere by the programmer. Thus, the 
first time MUMBLE is called, G(2) will be expanded as 002, G(k) 
as G$k, etc. 

At the end of a macro expansion, the generated symbol base 
value is incremented by the amount designated by the expression 
following the generated symbol name in the MACRO directive. This 
is h in the case of MUMBLE. Thus, the second call of MUMBLE will 
produce in place of G(2), G06, the third call will produce 0lfi, 
etc. It should be clear that the generated symbol name should 
be kept as short as possible. 

The expression in the macro head (call it m) must have a , 
value in the range [1,1023]. A generated symbol subscript must 
have a value in the range [l,m]. 
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Ki=/ 5 -^ ♦ 3 Concatenation 

Occasionally, it is desirable to have a dummy argument follow 
immediately after an alphanumeric character, for example, to 
have D(l) follow just after ALPHA. But then the assembler 
would not recognize the dummy because it would see ALPHAD(I) 
instead of D(l). To get around this problem the concatenation 
symbol * .&' is introduced. Its sole purpose is to separate a 
dummy argument (or conceivably a generated symbol) from a preceding 
alphanumeric character during macro definition. Thus, the example 
becomes ALPHA. &D(l). The concatenation symbol is not stored in 
string storage so it does not appear during expansion. 

As an example, say that we wish to define a macro STORE, 
and suppose we have established the convention that certain 
temporary storage cells begin with the letters A, B, or X 
depending on what register is saved there. The definition is: 



\sJ 



store macro d 

st.&d($) d(i) 

EKDM 



If called by the statements 

STORE B17 
STORE Xkh 

the macro will expand as 

STB B17 
STX Xkk 



The concatenation symbol may appear anywhere in a macro 
definition, but it is only necessary in the case described above. 
If one macro is defined within another, any concatenation symbols 
within the inner macro will not be removed during the definition 
of the enclosing macro. , 






5-23 

V. -' 5.k.k Conversion of a value to a dip; it string 

As an adjunct to the automatic generation of symbols (or 
for any other purposes for which it may be suited) a capability 
is provided in the assembler's macro expansion machinery for 
conversion of the value of an expression at call time to a 
string of decimal digits. The construct 

(Expression) 
will be replaced by a string of digits equal to the value of 
the expression. For example, if X=5 then 

AB($2*X+l) 
will be transformed into 

abh 

If the value of the expression is zero then the digit string is 
'0'; if it is negative then the digit string is preceded by a 
minus sign. 

This conversion scheme can also be used inside repeat blocks; 

for example 

O RPT (1=1,10) 

TEMP($l) BSS 1 
EKDR 

creates 10 cells labelled TEMPI through TEMP10. 
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5.1+.5 A note on subscripts 

The expressions used as subscripts for dummy arguments 
and generated symbols, as well as the expressions used in the 
conversion to a digit string must be absolute. Any undefined 
symbols appearing in these expressions are treated as if they 
were defined with the value -1. These expressions may themselves 
contain dummy arguments, generated symbols, and ($...), so 
constructs like ($^+D(l*D(3))) are possible. 
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5.5 NARG and NCHR Number of arguments and number of characters 

Macros are more useful if the number of arguments supplied 
at call time is not fixed. The precise meaning of a macro (and 
indeed, the result of its expansion) may depend on the number or 
arrangement of its arguments. In order to permit this, the 
macro undergoing expansion must be able to determine at call time 
the number of arguments supplied. The NARG directive makes this 
possible. 

NARG functions like EQU except that no expression is used 
with it. Its form is 

[ $] symbol NARG [ comment ] 
The function of the directive is to equate the value of the symbol 
to the number of arguments supplied to the macro currently 
undergoing expansion. The symbol can then be used by itself or 
in expressions for any purpose. NARG may appear in any macro, 
even one which has no dummy argument (and thus never has any 
( ) arguments at call time); it is an error for NARG to appear outside C/j 

a macro. 

It is also useful to be able to determine at call time the 

number of characters in an argument. NCHR functions by equating 

the symbol in its label field to the number of characters in its 

operand field. Its form is 

[ $3 symbol NCHR [character string [comment]] 

where "character string" has exactly the same form as an argument 

' supplied for a macro call, i.e., if it involves blanks, commas, 

or semi-colons it should be enclosed in parentheses (see section 

5.6). NCHR can appear anywhere, both inside and outside macros, 

but it is most useful in macros for determining!: the length of 

arguments. 

Examples : 

A NCHR ABCITCF A: =6 

B NCHR (,,XYZ,,) B:=7 

C NCHR D(I) C:«? 

o o 
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5 .6 Macro calls 

The format of a macro call is: 

[[$] label] macroname [argstring] [comment] 

Such a call causes the macro whose name appears in the 
opcode field to be expanded, with the dummy arguments in the 
macro body replaced by the actual arguments of the argstring. 

The label field is always transmitted as argument 0, so 
that D (el), where el has value 0, is always legal inside a macro. 
An occurrence of D(el), where el=0, will be replaced by the 
label field. If the label field is empty, then D(el) expands 
to the null string. At most seven characters will be transmitted 
this way: the first six characters of the symbol in the label 
field, preceded by '$' if the label field begins with '$'. 

If the user wishes to transmit an argument to a macro in 
the label field of the macro call, but does not wish to have 
the symbol in this field defined, he should define the macro 
with MACRO rather than MACRO. (See section 5 .k) An example: 

NT MACRO D 

RPT D(l) 

DATA D(2) 
ENDR 

D(0) DATA -D(l) 
EMM 

when called by: 

DTE NT U,i+B7 

expands as : 



DATA 


km 


DATA 


i+B7 


DATA 


1+B7 


DATA 


i+B7 


DATA 


-h 



DTE 

Notice that this would have caused a doubly-defined symbol 
error had MACRO been used rather than MACRO. 
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A macro call may or may not have an arg string (see section 
5.U). If an arg string is present, it may contain any number 
of arguments, in fact, more than are referred to by the macro. 

Before describing an arg string, the following should be 
noted: blanks, commas, semi-colons, and parentheses that are 
enclosed in single or double quotes are treated exactly like 
ordinary characters enclosed in quotes; they do not serve as 
terminators, separators, delimiters, or the like. In effect, 
when the argument collector in MRP is collecting arguments 
for a macro call., the occurrence of a quote causes it to stop 
looking for special characters except for a matching quote (and, 
of course, carriage return, which is an absolute terminator). 
A single quote enclosed in double quotes is not a special 
character and vice versa. Thus, when a blank, comma, semi-colon, 
or parenthesis is referred to in the following, it is under- 
stood that it is not enclosed in quotes. 

An arg string for a macro call has the following format: 

<arg>,<arg>, . . . ,<arg> <terminator> 

where a terminator is a blank, semi-colon, or carriage return. 
There are three forms of <arg> : 

1. <arg> may be the null string, 

2. If the first character of <arg> is not a left paren- 
thesis then <arg> is a string of characters not con- 
taining blank, comma, semi-colon, or carriage return 
(remember that blanks, commas, and semi-colons may 
appear in <arg> if they are enclosed in quotes). 

3- If the first character of <arg> is_ a left parenthesis 
the <arg> does not terminate until a blank, comma, 
or semi-colon is encountered after the right parenthesis 
which matches the initial left parenthesis ("matches" 
means that all left and right parentheses in the 
argument are noted and paired off with each other so 
that a nested parentheses structure is possible). 
Of course, a carriage return at any point immediately 






u 



o 



\J 
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terminates <arg>. Again, remember that blanks, commas, 
semi -co Ions, and parentheses enclosed in quotes are 
ignored when <arg> is being delimited. The initial 
left parenthesis and its matching right parenthesis 
(which need not be the last character in <arg>) are 
removed before <arg> is transmitted to the macro. 
Examples : 

AMAC (>2S2J ),,' HOUSE, ^ROGER'^AB")") 

D(l) = >2JU 

D(2) = null string 

D(3) = ' HOUSE, J30GER' 

D(U) = AB")" 

5 •! Examples of conditional assembly and macros 

1. It is desired to have a pair of macros SAVE and RESTOR 

for saving and restoring active registers at the beginning and 

end of subroutines. These macros should take a variable number 

of arguments so that, for example, one can write 

SAVE A, SUBRS 
RESTOR A,B,X,SUBRS 

to generate the code 



STA 


SUBRSA 


LEA 


SUBRSA 


LDB 


SUBRSB 


LDX 


SUBRSX 



To this end we first define a macro MOVE which is called 

by the same arguments delivered to SAVE and RESTOR, but with 

the string 'ST' or 'ID' appended. 

MOVE MACRO D 
X NARG 

RPT (Y=2,X-1) 

d(i)d(y) d(x)d(y) 

ENDR 
ENDM 

Now SAVE and RESTOR can be defined as 

SAVE 



MACRO 


D 


MOVE 


ST,D(,) 


ENDM 
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RESTOR MACRO D 

MOVE LD,D(,) 

ENDM 

2. Many programmers use flags, memory cells tha.t are 
used as binary indicators. The instruction SKN (skip if memory 
negative) makes it easy to test these flags if the convention is 
used that a flag is set (true) if it contains -1 and reset (false) 
if it contains 0. We want to define two macros, SET and RESET 
to manipulate these flags; furthermore, it is desirable to 
deliver at call time the name of an active register which will 
be used for the action. Calls of the macros will look like 

SET A , FLG1, FLG2 , FLG3 
RESET X,FLG37,FLG12 

As in the previous example we make use of an intermediate 
macro, STORE, which takes the same arguments as SET and RESET. 



STORE MACRO 
X NARG 
RPT 

ST.&D(1) 
ENDR 
ENDM 


D 

(Y=2,X) 
D(Y) 


SET and RESET are defined 


as 


SET MACRO 


D 



•V 



LD.&D(l) =-1 
STORE D(,) 

ENDM 

RESET MACRO D 
CL.&D(l) 

STORE D(,) 
ENDM 

3. The following macro, MOVE, takes any number of pairs 
of arguments; the first argument of each pair is moved to the 
second, but an argument may itself be a pair of arguments, which 
may themselves be pairs of arguments, etc. MOVE extracts pairs of 
argument structures and transmits them to a second macro M0VE1. 

( MOVE MACRO D (^S 

X NARG V ~ / 

RK! (Y=1,2,X) 
K0VE1 D(Y),D(Y+1) 

ENDR 
ENDM 
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The main work is done in M0VE1 which calls itself recursively 
■until it comes up with a single pair of arguments. 



M0VE1 KACRO 


D,G,2 


G(l) karg 




G(2) EQU 





IF 


G(l)=2 


IDA 


D(l) 


STA 


D(2) 


ELSE 




RPT 


G(l)/2 


M0VE1 


D(G(2) 


EWDB 




ENDF 




ENDM 




When MOVE is called by 




MOVE 


A,B 


the code generated is 




LDA 


A 


STA 


B 



When called by 



MOVE 



A,B,C,D 



the code generated is 



LDA 


A 


STA 


B 


LDA 


C 


STA 


D 



When called by 



the code generated 



MOVE 


(A,B),(C,D) 


is 




LDA 


A 


STA 


C 


IDA 


B 


STA 


D 



4^- 



5-31 

O 

And when called by 

MOVE ((A,B),(C,D)),((E,F),(G,H)) 

the code generated is 



O 



IDA 


A 


STA 


E 


LDA 


B 


STA 


F 


LDA 


C 


STA 


G 


LDA 


D 


STA 


H 



It is instructive to trace the last example by hand to see how 
the recursive calls of M0VE1 work. This is an exercise left 
to the reader. 



o 



o 
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6.0 Oneratlry-r HARP 

^ • ■*- Error comment--: on statements 

When EARP encounters a statement which it deems incompre- 
hensible or illegal, it lists the statement in error-format 
(corresponds to all listing format booleans being set) and then 
on the following line(s) lists all error comments pertaining 
to the statement. 

Most error- comments are as intelligible as the situation 
( and MRP's strangeness) allows. Some of the more common 
and/ or more obscure ones are listed and commented upon below: 

C ? The character C caught HARP unawares 

BAD TERMINATION Premature termination, or garbage (like 

extraneous commas) where tne statement 
should end. 

LC OVERFLOW The value of the location counter got 

out of the range [0, 37777 B] . 

DIRECTIVE OUTSIDE BODY And ENDF, ENDR, or ENDM without a 

matching IF, RPT, or MACRO. 

(symb) REDEFINED "symb" was defined (as a label) previous 

to this definition of it. 

(symb) OPCODE? "symb" was used as an opcode and is not 

in the opcode table. 

UNDEFINED EXPRESSION An undefined symbol occurs in an 

expression which should be defined. 

6.2 Other error comments 

If a fixed-length table ever flows, a message (name) 
OVERFLOW is printed (after a listing of the offending statement 
in error-format), followed by *****ASSEMBLY DEAD***** and 
termination of one assembly. 

The name may be: 

MAIN TABLE Contains opcodes, literals, symbols 

(both undefined and defined) . 

(?\ STRING STORAGE Contains MACRO definitions, macro calls 

and RPT expresions. 



i 



EXPRESSION TABLE 



INPUT POINTER STACK 



CHARACTER STACK 



OPERAND STACK 



PILE 
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Contains post-fix Polish representations 
of expressions containing undefined 
symbols, until all the symbols in the 
expression are defined. 

Contains one entry for each embedded 
change of input-source. 

Holds the characters in a symbol while 
they are being collected. 

Holds operands in the processing of 
expressions. 

Space for temporaries in recursive calls 
of the expression eater. 



O 



In addition, the following comments may appear 
TRAP AT XXXXX 



1-0 ERROR 

NO END DIRECTIVE 



Error committed by NARP at location XXXXX; 

assembly terminates. 

Error in input or output of information, 
assembly terminates . 

An end-of-file encountered before an 
END directive; assembly will terminate 
as though an END directive was given 
(i.e., normally). 



(fiff-nfcK 






O 
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c 



6.3 Starting an assembly 



Assuming that the user has entered the time-sharing system, 
NARP is called by hitting the rubout button until the exec 
answers (by typing '&' ) and then typing 'NARP' followed by a dot. 
Control is then turned over to NARP and a source file must be 
specified; other information may also be supplied, if desired. 
The general format is: 

default convention 



Skarp. 
source file: 
object file: 
[text file: 


file name 
file name 
file name] 


none 
none 
TELETYPE 



Each line above is either terminated by a dot or a semi-colon. 
A dot causes assembly to begin immediately (except after the 
source file name). The default conventions are used for all 
those options not explicitly specified. A semi-colon causes a 
carriage return to be typed, and the specification of some 
option is expected. 

The various options are discussed in more detail below: 
SOURCE FILE: As soon as NARP is started this line is typed and 
the user must specify a file containing a program 
to be assembled. When he terminates the name, 
WARP responds with 'OBJECT FILE:' on the next line. 
OBJECT FILE: The file name given specifies where the binary 
output from the program should go. If the file 
name is terminated by a semi-colon, then a 
carriage return is typed and NARP waits for 
one of the following options to be specified. 
TEXT FILE: The file name given specifies where the listing 
of the source program and of the error messages 
should go. This option may be specified only once. 



C' 
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( v_ ' Appendix A: List of all pre-defined opcodes and -pre-defined symbols 

The following table is a listing of an initialization program 

used to initialize the opcode table and symbol table of NARP. 

It will be noted that in some cases the OPD directive has four *' 

•v 

operands instead of the usual three; the fourth operand specifies 
the type (directive, macro, or instruction) of the opcode being 
defined. It is only possible to use four operands for OPD when 
NARP is being initialized, and once the initialization program 
has been assembled, OPD will only accept three operands. 



o o 



c- o 



JJ * MARP INITIALIZATION PROGRAM. 



(? 1 NOV 1956) 



* OPP SYNTAX AwO SEMANTICS; 

* <SYi vl POL> OPP <VALl'5:>C ,<OP SIT >I , <SPI FTK >[ , <TYPF>] 1 ] 

• CI - OPERAND OPTIONAL 

1 - NO OPERAND 
? - OPERAND RFOUIPEP 



* 


<OPSIT> 


* 




* 




* 


<SHIFTK> 


* 




* 


<TYPF> 


* 




* 







! 



NORMAL INSTRUCTION 
SWIFT INSTRUCTION 



O - INSTRUCT I ON 
! - DIRECT I VE 
2 - MACRO 



* INSTRUCTION DEFINITIONS: 



CZ> 



LDA 


OPP 


STA 


OPD 


LPP 


OPD 


STP 


OPD 


LPX 


OPD 


STX 


OPD 


FAX 


opp 


XMA 


npD 


ADC 


OPD 


ADC 


OPP 


AP*1 


OPP 


*1If! 


npo 


SUF 


opp 


sue 


OPD 


■XUL 


opp 


01 V 


OPP 


FTP 


OPD 


Ypn 


OPD 


FOR 


OPD 


FCH 


OPP 


CLA 


OPD 


CLP 


OPD 


'"M * R 


OPP 


clx 


OPD 


CLFAR 


ipp 


CAR 


opn 


CPA 


opp 


XAP 


opp 


PAC 


npn 


A r <C 


OPP 


CXA 


OPD 



7.7 fid 

03 5 Pi 
0750 
013 60 

R710 
03 70 
C1770 
OS20 



00O0B 
0000B 
00 op, 
0000B 
0000B 
000 op 
000 OB 
0O00P 



05 50H000P ,f> 
O5 7O0OOOP .?. 



061000OOB,? 
05 4 00003,? 
05 6O000OF , ? 

640000 OP, ? 
065 000O0B ,2 

0! 4O0O07IB,? 

01 60 00 OP, ?, 
01 7O0 00 0R,? 



04 6000 
04 6000 
'34 60 00 
046000 
246000 
P.4 6O00 
0^6^00 
04 6000 
04 6000 
0/I6000 
046000 
4 60 0?, 



OOP,? 
015 , 1 

0?F , 1 
03B , ! 

OP , 1 
03F , 1 
04B , 3 

1 9P , i 
1 4P , 1 
1 ?E , 1 
05P, 1 
OOP, 1 



LOAD A 

STORF A 

LOAD B 

STORF B 

LOAD X 

STORE X 

COPY EFFECTIVE 

EXCHANGE M AND 



ADD 



ADDRESS 
A 



INTO X 



y\ TO A 
ADD WITH CARRY 
ADD A TO y< 
MEMORY INCREMENT 
SUBTRACT "1 FROtf a 
SUBTRACT WITH CARRY 
MULTIPLY 
DIVIDE 

EXTRACT (AND) 
ME0.GF (OR) 
EXCLUSIVE OR 



FECI 
CLFA 
CLFA 
CLFA 
CLE A 
CLE A 
COPY 
COPY 

COPY 
COPY 
COPY 



STFR 

R A 

R B 

R AB 

R X 

R A, 
A I 
B I 

A NOP 
B I 
A I 
X I 



CHANGE 



P, AND 

MTO B 

NTO A 

A AMD 

MTO A, 

NTO P, 

MTO A 



CLFAR IMG 
CLEARING 



v_<x 


OPD 


XXA 


DPP 


CBX. 


npn 


* CXB 


OPD 


xxb 


OPn 


STF 


OPD 


LDE 


OPD 


X^F 


OPD 


CMA 


OPD 


AXC 


OPD 


PPU 


OPD 


PFX 


OPD 


8 PM 


OPD 


PRR 


npn 


BR I 


npn 


SKS 


npn 


SKF 


n?D 


5KG 


OPD 


SKP 


npn 


SKM 


OPD 


SKN 


dpd 


SKA 


OPD 


SKB 


OPD 


/■ ^KO 


OPD 


KSH 


OPD 


RCY 


opn 


LPSR 


OPD 


LSH 


OPD 


LCY 


OPD 


MOD 


OPD 


HLT 


OPD 


ZRO 


OPD 


NOP 


OPD 


EXl! 


OPD 


PPT 1 


DPD 


PPT 2 


OPD 


BPT3 


OPD 


PPT4 


OPD 


pnv 


OPD 


RED 


OPD 


nvT 


OPD 


OTO 


OPD 


FIR 


OPD 


DIP 


OPD 


('' MP 


nPD 


OPD 


IDT 


OPD 



0/; 600 4 08, 1 

04 6000208, 1 
046000408, 1 

04 60 00 60? f ! 

046005228 , i 

04 6001 /i0R, 1 
0/j6O01 608, i 
?u60i 0008 , i 

'/! 4^004 51 IP , 1 

001 000008,2 

04 1000008 ,2 
043000O0P,2 

05 1000008,2 
01 1000008,2 



00 713R,?. 
00C0B , 2 
0000B, 2 
CI » 55 PIP ,2 

S0000B,2 



0/J000000B,2 

05 00 

73O 

O600 

70 

^530 

^ 72 00008,2 

052000008 ,2 

74 00 00 08.2 



066000008,2, 1 
066200008,2, 1 
066240008,2, 1 
067000008,2, 1 
067200008,2,1 
067103008,2,1 

000000008, 
000000008,0 
020000008,0 
023000008,2 

04020400B, 1 
04 020200B, 1 
040201 00B, 1 
04020O4 08 , 1 

0220000 IE , 1 
022000 108, 1 
02230 10 IB, 1 
02200 I 008, 1 

002200028, 1 
0022 00 048 , i 
00220020B, 1 
04 0200028 , ! 
04 020004B, 1 



A 



R 



COPY A INTO X 
EXCHANGE" X AMD 
COPY 8 INTO X 
COPY X INTO 8 
FXCMANGF X AMD 
STnPp EXPONENT 
LOAD EXPONENT 

exchange exponents 
copy negative of a 
copy a to x, clear 



o 



INTO 
A 



BRANCH UNCONDITIONALLY 

INCREMENT INDEX AND BRANCH 

MARK PLACF AMD BRANCH 

RETURN BRANCH 

BRANCH AND RETUPN FPOM INTERRUPT 

SKIP IF SIGNAL NOT SET 

SKIP IF A EQUALS M 

SKIP IF A GREATER THAN M 

RFDUCE M, SKIP IF NEGATIVE 

SKI? IF A EQUALS M Of! E Y 'ASK 

SKIP IF M NEGATIVE 

SKIP IF M AND A DO MOT COMPARE O^S 

SKIP IF M AND P DO NOT COMPARE ONES 

DIFFERENCE EXPONENTS AND SKIP 

RIGHT SHIFT AB 

RIGHT CYCLF AB 

LOGICAL RIGHT SHIFT AB 

LEFT SHIFT AB 

LEFT CYCLE AB 

NORMALIZE AND DECREMENT X 

HALT 

ZERO 

MO OPERATION 

EXECUTE 

BREAKPOINT TEST 1 
BREAKPOINT TEST 2 
BREAKPOINT TEST 3 
BREAKPOINT TEST 4 

RESET OVERFLOW 
RFCORD EXPONENT OVERFLOW 
OVERFLOW TFST AND PESFT 
OVERFLOW TEST ONLY 

ENABLE INTERRUPTS 
DISABLE INTERRUPTS 
ARM /DISARM INTERRUPTS 
INTERRUPT ENABLED TEST 
INTERRUPT DISABLED TFST 



u 



o 






\i>~-- 



ALCV 


OPD 


DTSV 


OPD 


A SCW 


OPD 


TOPW 


OPD 


CATW 


OPD 


CFTV 


OPn 


ZTV* 


OPD 


CITV 


OPD 


F.op 


OPD 


M I W 


OPn 


VI M 


OPD 


PIM 


OPD 


POT 


OPD 


EOM 


npo 


pr T w 


OPD 


BPT'>' 


OPD 


pio 


OPD 


PRS 


OPD 


CIO 


OPD 


CTRL 


OPD 


dpi 


OPD 


DPO 


OPD 


DWI 


OPD 


D'>'0 


OPD 


EXS 


OPD 


FAD 


OPD 


FDV 


OPD 


EMP 


OPD 


FSR 


OPD 


GCD 


HPD 


CCI 


OPD 


ISC 


OPD 


1ST 


OPD 


LAS 


npn 


LOP 


OPD 


ost 


OPD 


SAS 


OPD 


SBRM 


OPD 


SBRR 


OPD 


SIC 


OPD 


SKSF 


OPO 


SKSG 


OPD 


ST I 


npn 


ST'"' 


OPD 


STP 


OPD 


TCI 


OPD 


TCO 


OPD 


yen 


npn 


VCH 


npn 


VCI 


OPD 



0025^000F,1 ALFPJ CHANMFL W 

00200000B,1 DISCOMMFCT CHANMFL V 

002120008,1 ALFRT TO STORF ADDRESS IN CHANNEL W 

W?AWW& t l TERMINATE OUTPUT ON CHAMN~L V '' i 

' y 1 

554 01 400OB, 1 CHANNFL ACTIVF TFST I 

040! 1030R, 1 CHANMFL W ERROR TFST I 

040120008,1 CHANMFL W COUNT TFST ! 

040100008.1 CHANNEL V INTER-PFCORD TEST i 

O0600PI7I0B 5 2 ENERGIZE OUTPUT D j 

01 200^0518, 2 >*] niTO V BUFFER Wpr^ F^PTY ! 

032000008.2 W BUFFER INTO M WHEN FULL ': 
033000008,2 PARALLEL INPUT > 
01500^008, 2 PARALLEL OUTPUT i 
00200^008,2 FNFRGIZF OUTPUT M 

04 0?7,c?t i?iR 9 i i ; i PUFFER ERROR TEST ■ 

040210008.1 v BUFEFR READY TEST ' 

576000008.2 BLOCK I/O 

5 730O000B 9 2 BRANCH TO SYSTEM 

5 SI 00 08,2 CHARACTER I/O > 

5 72000008,2 CONTROL > 

5 4200000P,2 DRUM BLOCK INPUT 

54300000B,2 DRUM B] OCX OUTPUT I 

5 4 4000008,2 DRUM WORD INPUT '[ 

545000008,2 DRUM WORD OUTPUT - 

5 52000008,2 FXFCUTF INSTRUCTION IN SYSTFM MOPE ! 

5 5 6000008,2 FLOATING ADD j 

5 53000008,2 FLOATING DIVIDE 

554000008,2 FLOATING MULTIPLY ! 

555000008,2 FLOATING SUBTRACT S 

537000008,2 GFT CHARACTER AND DECPEMFNT [ 

5S500000B,2 GFT CHARACTER AMD INCREMENT * 

54!00000B,2 IMTEPNAL TO STRING CONV. (FLOATING OUTPUTS 

550000008,2 INPUT FROM SPFCIFIED TELETYPE 

54(S00000B,2 LOAD FROM SFCONDARY MEMORY 

566000008,2 LOAD POINTER CAB) 

55100000B,2 OUTPUT TO SPFCIFIFD TFLETYPF 

547000008,2 STORF IN SECONDARY MEMORY 

5 70000008,2. SYSTEM PRM 

05 1400008,2 SYSTEM BPR 

5400000Op,2 STRING TO INTERNAL CONV. (FLOATING INPUT) 

563000008,2 SKIP IF STRINGS FOUAL 

562000008,2 SKIP IE STRING GREATER 

536300008,2 SIMULATF TELFTYPF INPUT 

53400000P, ,2 STEAL TTY OUTPUT 

567000008,2 STORE POINTER (AP ) 

5 74000008,2 TELETYPE CHARACTER INPUT 

5 75000008,2 TELETYPE CHARACTER OUTPUT 

535000006,2 WRITE CHARACTER AND DECREMENT 

564000008,2 WRITF CHAPACTFR 

557000008,2 WRITF CHARACTER AND INCREMENT 



r 



OPD 



5 600 00B,2 



WORD I/O 



* DIRECTIVE DEFINITION 



ASC 


npn 


fl ? 1 


HP'S 


P P 


1,2,0,1 


PSS 


OPP 


? , 2 , « , i 


COPY 


OPP 


^ ? 1 


CRPT 


OPP 


4,2,3,1 


PAT A 


OPP 


5,9,0,1 


PEC 


n?p 


7 1 fl 1 


PELSY M 


npn 




ELSE" 


OPP 


y , 1 , ft , J 


ELSF 


OPD 


10 , 2 , , 1 


END 


OPD 


11,1,0,1 


FNDF 


OPP 


12,1,0,1 


E N P M 


OPD 


13,1,8,1 


ENPR 


OPD 


14,1,3,1 


EQU 


OPD 


i'Z> v Y.i t f> i \ 


EXT 


nPD 


16,0,0, 1 


FREEZE 
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